@database PaletteTool.guide @node Main "PaletteTool" PaletteTool - A Public Screen palette for 8 or more colors Copyright 1994 by Timothy B. Kreuzer. All rights reserved. Version: 1.4 Author: Tim Kreuzer (and the KreuzerSoft support team) Language: SAC/C V6.5 @{"Features" link features} @{"Limitations" link limitations} @{"Release Notes" link releasenotes} @{"Notes from the Author" link notesfromtheauthor} @{"Why PaletteTool?" link whypalettetool} @{"Terminology Disclaimer" link terminologydisclaimer} @{"Starting PaletteTool" link startingpt} @{"Main PaletteTool Window Description" link mainptwindowdescription} @{"Palette Window Description" link palettewindowdescription} @{"ColorByName Window Description" link cbnwindowdescription} @{"Iconified Window Description" link iconwindowdescription} @{"Basic PaletteTool Operation" link basicptoperation} @{"Icon Tooltypes" link icontooltypes} @{"Credits" link credits} @{"Contacting the Author" link contactingtheauthor} @{"Legal Stuff" link legalstuff} @{"KreuzerSoft Products" link kreuzersoftproducts} @endnode @node features "Features" Opens and operates on the default public screen Gadtools-based user interface, with keyboard equivalents for many of the program functions Full 8 bit RGB support Full AmigaDOS 3.0-compliant locked pen "protect" mode as well as standard "free" mode Fully integrated "color by name" selection, with a built-in database of 507 colors Supports the follow actions: - color spread (multi-directional) - individual color copy - individual color exchange - rotation of palette in both direction - cycling of entire palette in both directions with adjustable cycle speed - individual color "show" (flash selected color) User interface consists of separately controllable windows for: - main functions - color palette (2 sizes) - "color by name" selection Features a single-level "undo" capability Iconifiable, with color cycling controls also available from the programs iconified state Features ability of pick a pen/color from anywhere on the current screen (using the mouse pointer and either the space bar or middle-mouse-button). This type of color "pick" can also be used with the copy, spread, and exchange actions Freatures a "panic" restore button (and key equivalent) so you can restore the palette to where it was at program start "Smart" iconify function Help text (displayed on screen banner) for the copy, spread, exchange, and pick actions Upon exit, restores palette to where it was at start-up Single version for 68020 and up CPUs (all AGA Amigas) Tested OK using the Enforcer @endnode @node limitations "Limitations" Can only be used from the Workbench (start via Icon) Requires AmigaDOS 3.0(+) and the AGA chipset Requires a 68020(+) CPU Designed for use with higher-resolution screen modes (640x400 and higher). Note that this does NOT mean the program will not work on lower-resolution screens. What it DOES mean is that you may find the programs windows take up a lot of screen "real estate" on lower-resolution screens For some reason, the "pick" capability (using the space bar and/or middle-mouse-button) does not work correctly when using any of the screen modes supplied by EGS Spectrum graphics boards. I'm guessing this is a problem with the EGS "Amiga screen" emulation @endnode @node releasenotes "Release Notes" ----------------- Version 1.4 Notes ----------------- Completed reworked the user interface: - Moved the palette display to a separate window - Palette window can be displayed in two (user selectable) sizes - Added keyboard equivalents - Palette cycling controls now available on the iconify window as well as the main control window Added the (incremental) palette rotation capability Added the color exchange capability Added the keyboard equivalents Reworked major sections of the source code ------------------ Version 1.3b Notes ------------------ Fixed bug which caused inaccurate color "Spread" to occur while in the "Protect" palette mode ------------------ Version 1.3a Notes ------------------ Fixed bug which caused the 3 pointer colors to be skipped on a Spread action in "Free" mode (would only see this on screens with 32 or more pens). I really apologize for this, as I am very picky about only uploading fully tested programs! ----------------- Version 1.3 Notes ----------------- Screens with a minimum of 8 colors now supported Added "color by name", "panic restore", "pick from screen", full AmigaDOS 3.0 palette "protect" mode, and "free" mode capabilities. Note that "protect" mode takes the place of the old "hardcoded" method of avoiding pens/colors used by the system Fixed bug in "Iconify", where the previous positions of the main PaletteTool window and the inconified window were not restored when they (re)opened. Windows were opening at a fixed location (yech!) The currently selected pen/color in the main palette display is now recessed, allowing for easier visual confirmation Main palette gadget is no longer disabled during cycling Miscellaneous code and user interface cleanup ----------------- Version 1.2 Notes ----------------- Added full 8-bit RGB support (Hurray!) Added Iconify ("I" button) support Added About ("?" button) Added support for "X" and "Y" icon tooltypes to determine position of PaletteTool window at startup Corrected the Spread function's math to allow "smoother" spreads PaletteTool will no longer open on a screen that supports less than 32 colors; a nice requester will pop up to remind you of this if you try Fixed problem where original palette was not correctly restored upon quiting following certain types of Undo actions Fixed problem where the currently selected color's RGB slider values were not correctly reset after an Undo action All other features operate the same as in version 1.1 ----------------- Version 1.1 Notes ----------------- Added the Copy, Undo, and Spread capabilities Added the "restore palette at exit" capability All other features operate the same as in initial release version The loading and unloading of the palettes at the beginning and end of cycling can lock up your Amiga for 1 second or so DON'T PANIC IF THIS SHOULD HAPPEN! OK? Sorry for yelling! @endnode @node notesfromtheauthor "Notes from the Author" Upon release of V1.3 of PaletteTool, the program grew in size by about 100%. The biggest reason for the size increase was the addition of the color-name database. With this version (V1.4) I've managed to keep the program size roughly the same as before (approx 46K bytes) while adding a lot of new features. I'd like the get the program "smaller" if possible, and will continue looking for ways to do this. I decided a few versions ago that separate executables for 68020/30/40 CPUs were really not needed, as the most "intensive" thing PaletteTool does is cycling. I really didn't want to use the "space bar" for the "pick" action, but I don't know any other method (short of middle or right mouse button). I ran into weird system-lockup problems trying to trap an IDCMP window inactiviate (and update the gadgets) when the left mouse button was pressed outside the PaletteTool window. I also didn't want to use the right mouse button because of their standard use with menus. The creation and evolution of PaletteTool has served as a wonderful introduction-to and expansion-of my learning more about both the "C" programming language and the Amiga. It's a real joy developing code on such a wonderful machine (and operating system). @endnode @node whypalettetool "Why did I create PaletteTool?" 18 months ago, after deciding to take the plunge and buy an A4000 (which, by the way, is a fantastic machine!), I was disappointed in the lack of applications which exploited the increased color capabilities of 3.0/AGA. I went about creating some simple, yet fun, graphics programs with would exploit the color modes above 16 (see my Fractal, Lyapunov Space, and Terrain uploads). Then I realized that these graphics programs needed some type of palette control. This need resulted in the creation of PaletteTool, the latest version of which you are now reading about. I decided that is was much better to implement the palette control for these applications as a separate utility, rather than embed it within each program. That way, the palette control could be used along with any program which operates on a (default-able) public screen (like the Workbench). NOTE that PaletteTool can be used to alter the color palette of ANY Workbench or default Public Screen which supports at least 8 colors. It's functioning is NOT in any way dependant upon the presence of my Fractal, Lyapunov Space, or Terrain programs. Regarding the "color by name" facility: I don't know about you, but I am terrible at trying to "roll my own" colors using RGB sliders! @endnode @node terminologydisclaimer "Terminology Disclaimer" I have a bad tendency to use the terms "color", "pen", and "register" somewhat interchangably. From this point forward, I will be adopting the following: "Pen" - Will be used to denote one of the physical "slots" which can can hold a single set of RGB values. For example, if you have an 8 color screen, you actually have 8 pens available. Each of these pens can hold a different color. "Color" - Will be used to denote a distinct set of RGB values, which may also have a name at times (like "light blue"). "Register" - The same as "Pen" in my book. I will try and use "Pen", however, as Commodore uses this term. @endnode @node startingpt "Starting PaletteTool" Just click on the PaletteTool icon. PaletteTool will detect the number of pens available on the default Public Screen, and open it's window on this screen. Note that the Workbench screen is the standard default Public Screen. My PST (Public Screen Tool) program can be used to open a Public Screen at any AmigaDOS 2.04(+) supported resolution and depth. This includes any graphics boards which add entries to the Amiga's display database (like the EGS Spectrum). PST is available on many fine BBS's. I strongly recommend you get (and use!) PST if you are interested in running programs (like my Palette/LyapunovSpace/Terrain programs) on public screens other than the Workbench. Like PaletteTool, PST is in no way dependant/tied-into my other programs. It is a full, stand-alone utility in it's own right. @endnode @node mainptwindowdescription "Main PaletteTool Window Description" The main PaletteTool window consists of the following items: 1) Palette @{"Closed/Open" beep 0} @{"Sm/Lg" beep 0} Key equivalent is either "p" or "P". The "Closed/Open" cycle gadget controls the opening/closing of the window containing the actual screen palette. The "Sm/Lg" cycle gadget controls the size of the window containing the actual screen palette. Within this separate window, you can optionally select (using the pointer and the left-mouse-button): - the pen to be modified by the Red/Grn/Blu sliders - the pens associated with copy, spread, and exchange actions. - the pen whose color is to be "flashed" by the "Show" button The currently selected pen is recessed within the palette gadget. 2) ColorByName @{"Closed/Open" beep 0} Key equivalent is either "n" or "N". The "Closed/Open" cycle gadget controls the opening/closing of the window containing the "color by name" database. This ColorByName window is where you can choose RGB values for the currently selected pen by simply left-clicking on one of the names in the scrolling list. The ColorByName window can be positioned independently of the main PaletteTool window. The location of the ColorByName window will also be restored upon un-iconifying. However, when the ColorByName window is closed using the "ColorByName" button, it will re-open immediately adjacent to the main PaletteTool window. 3) A box which displays the color of the currently selected pen (on the middle-right side of the window). 4) @{"Red" beep 0} @{"Grn" beep 0} @{"Blu" beep 0} Sliders Three color modification sliders, one each for the Red (Red), Green (Grn), and Blue (Blu) color components. These affect the color of the currently selected pen. 5) @{"Copy" beep 0} Button Key equivalent is either "c" or "C". Allows the copying of one pen's color into another pen. To perform a copy: - first select the pen whose color is to be copied - hit the "Copy" button - then select the pen where that color should be copied-to NOTE that you can either pick the copy-to color from the Palette window >> OR << use the "Pick" button to select the copy-to color from anywhere on the screen. 5) @{"Sprd" beep 0} Button Key equivalent is either "s" or "S". Allows spreads (gradients) between the colors of two selected pens. To perform a "spread": - first select the starting pen - hit the "Sprd" button - then select the ending pen The colors of each intermediate pen will then be changed to a smooth gradient between the staring and ending pen colors. NOTE that you can either pick the spread-to color from the Palette window >> OR << use the "Pick" button to select the spread-to color from anywhere on the screen. 6) @{"Excg" beep 0} Button Key equivalent is either "x" or "X". Allows the exchange of one pen's color with another pen's color. To perform an "exchange": - first select the starting pen - hit the "Excg" button - then select the containing the color you wish exchanged with the previously selected pen NOTE that you can either pick the exchange-with color from the Palette window >> OR << use the "Pick" button to select the exchange-with color from anywhere on the screen. 7) @{"Undo" beep 0} Button Key equivalent is either "u" or "U". Restores the palette pen colors to how they were prior to the immediately previous color action (Copy/Spread/Exchange). Note that I said "how they were prior to the immediately previous action". Don't get confused and think that the program is acting up when you do an Undo, and some individual pen color mods you have made since the last Copy/Sprd/Excg get wiped out! IMPORTANT - Repeatedly selecting Undo will toggle the palette between where it was (before the last Copy/Spread/Exchange) and where it is (before you selected Undo). Try this to get a better (or any) sense of what I'm trying to explain ;v). 8) @{"Protect/Free" beep 0} Cycle Gadget "Protect" means that PaletteTool will pay special attention to those pens which it determined were locked at the time PaletteTool was started. A pen can be locked by any 3.0-aware program (like AmigaDOS). Examples of locked pens would be those used to render the Intuition windows, menus, and gadgets (background/borders/text/buttons/etc.) What "Protect" means to you is that: - You will be unable to select a locked pen from the palette gadget - The spread action will "skip over" the colors in any locked pen - The cycle action will "skip over" any locked pen - The "Pick" function will not select a locked pen, even when the screen color you pick is contained in one of the locked pens "Free" means that PaletteTool will not pay ANY attention to locked pens. This mode is what you are probably used to in all the other palette programs you are using. What "Free" means to you is that: - You will be unable to select any pen from the palette gadget - The spread action will affect the color of EVERY "in between" pen - The cycle action will cycle EVERY pen's color - The "Pick" function will always result in the selection of a pen Obviously, CARE MUST BE EXERCISED while in "Free" mode, or you can quickly hose things up (i.e., end up with an unreadable screen). That's why I added the "panic reset" button ("Reset") with it's "R" key equivalent. You can always reset the screen palette to where it was at PaletteTool startup by either: - Selecting the "Reset" button >>OR<< - Pressing the "R" key on your keyboard At startup, PaletteTool attempts to set the palette mode to "Protect". If, however, it finds that ALL the screen's pens are locked, it opens in "Free" mode. When this occurs, the "Protect/Free" cycle gadget is disabled. 9) @{"Show" beep 0} Button Key equivalent is either "h" or "H". Flashes the color of the currently selected pen. This comes in handy if you are looking at a screen with a lot of similar (or just a lot of) colors, and are curious as to which pen is responsible for that color. 10) @{"Pick" beep 0} Button Key equivalent is either "i" or "I". Allows you to select a pen by picking any color on the current screen via the mouse pointer. To use, first select the "Pick" button. Some (hopefully) descriptive text will then be displayed in the current screens banner (at the top of the screen), and the "Pick" button will disable, reminding you that you're doing a "Pick". Move the mouse pointer (anywhere on the screen), until it is over the desired color. DO NOT PRESS THE LEFT MOUSE BUTTON WHILE YOU'RE "PICK"ING - one of the displayed PaletteTool windows (main/palette/colorbyname) must be active when you're doing your "pick". To select the pen associated with this color, either: - Press the space bar on your keyboard >>OR<< - Press the middle button on your mouse (if you have 3 button mouse) The reason I asked you not to press the left mouse button during the "Pick", is that either the PaletteTool or ColorByName windows must be active for the "Pick" to work. If you're having problems with "Pick": - Make sure either the PaletteTool, Palette, or ColorByName windows are active by left-clicking on either window border - Don't forget that in "Locked" mode, PaletteTool will NOT select a locked pen (which in this case is being located via "Pick") - If you're using a commodity which traps the middle-mouse-button, PaletteTool may not "see" this button press. You can always use the space bar in this instance. 11) @{"Cycle" beep 0} Button Starts/stops the cycling of the pen colors in the current palette. Press once to start cycling. Press again to stop cycling. See the "Protect/Free" palette mode discussion (#8) above for important info relative to "Cycle". Note that all non-cycle-related sliders/buttons/etc. are disabled while cycling is in progress. 12) @{"Fwd/Rev" beep 0} Cycle Gadget Controls the direction of the color cycling. Fwd = Forward Cycle Rev = Reverse Cycle Note that the cycle-direction control is ACTIVE during cycling (i.e., you can change directions while you are cycling). 13) @{"Spd" beep 0} Slider Control the speed of the color cycling. Values range from 1 (= slowest) to 20 (= fastest). Note that the cycle speed control is ACTIVE during cycling (i.e., you can change speeds which you are cycling). 14) @{"<" beep 0} and @{">" beep 0} Buttons Incrementally shift the palette in either the left (<) or right (>) direction. Key equivalent for "shift left" is either "<" or the cursor-left (arrow) key. Key equivalent for "shift right" is either ">" or the cursor-right (arrow) key. 14) @{"Reset" beep 0} Button Key equivalent is either "r" or "R". Restores the screen palette to where it was when PaletteTool was started. 15) @{"I" beep 0} Button Iconify. Closes all PaletteTool windows and opens into a single small window (known as the "iconified" window). Color cycling is available from this "iconified" window, using the same cycling controls as specified above. Pressing the Open button in the "iconified" window will reopen the PaletteTool window(s) 16) @{"?" beep 0} Button About the program/author. Opens an info requestor. @endnode @node palettewindowdescription "Palette Window Description" The current screen palette (pen color display) is displayed in a separate window (named "Palette"). The opened/closed state and size (Sm/Lg) of the Palette window is controlled via the main PaletteTool window. Within the Palette window, you can optionally select (using the pointer and the left-mouse-button): - the pen to be modified by the Red/Grn/Blu sliders - the pens associated with copy, spread, and exchange actions - the pen whose color is to be "flashed" by the "Show" button The currently selected pen is recessed within the palette display. The Palette window can be positioned independently of the main PaletteTool window. The location of the Palette window will also be restored upon un-iconifying. However, when the Palette window is closed using the "Palette" button, it will re-open immediately adjacent to the main PaletteTool window. Both the "Small" and "Large" palette displays are fixed in size. Therefore, the displayed size of each pen's color in the palette decreases as the number of screen pens increases (AKA screen depth). The pens are displayed in "row sequential form" from left-to-right and top-to-bottom. Therefore, the first row in the palette display consists of pens 0, 1, 2, 3, 4, etc. I was working on a resizable palette display window, but Commodore's GadTools library does not support a resizable palette gadget. This means I would have to do a window close/re-open when the user resized the palette window. After experimenting with this, I decided I didn't like the way it worked (I hate "working around" things), so I abandoned that method. @endnode @node cbnwindowdescription "ColorByName Window Description" The ColorByName window is where you can choose RGB values for the currently selected pen by simply left-clicking on one of the names in the scrolling list. The opened/closed state of this separate window is controlled via the main PaletteTool window. The ColorByName window can be positioned independently of the main PaletteTool window. The location of the ColorByName window will also be restored upon un-iconifying. However, when the ColorByName window is closed using the "ColorByName" button, it will re-open immediately adjacent to the main PaletteTool window. @endnode @node iconwindowdescription "Iconified Window Description" The iconified PaletteTool window replaces the other PaletteTool window(s) when you select the "I" button on the main window. The full set of palette cycling controls are available from this iconified window. The controls perform identically to those on the main PaletteTool window. The last location of the iconified PaletteTool window will be restored when you re-iconify. @endnode @node basicptoperation "Basic PaletteTool Operation" You select a pen for modification (or just viewing) by left-clicking on one of the colors in the palette display. This becomes the "active" pen. The "currently selected pen's color" box on the middle-right side of the window will change to show you the color associated with the pen you just picked. Once a color is selected, it's RGB components can be modified by using the three Red/Grn/Blu sliders. See the "... Window Description" section for specific guidelines. I intended PaletteTool to be somewhat intuitive in how it works, so I hope the lack of detailed directions is not an issue. If you have any specific questions on PaletteTool's operation which don't seem to be covered by this file, please contact me and I'll do my best to help you out. @endnode @node icontooltypes "Icon Tooltypes" PaletteTool recognizes the following Tooltypes within it's icon: X= - The X-coordinate at which the PaletteTool main window will initially open. Y= - The Y-coordinate at which the PaletteTool main window will initially open. If these tooltypes are not present, the PaletteTool main window will open at coordinates X=10 Y=10. @endnode @node credits "Credits" The GUI for PaletteTool was developed using Jan van den Baards' wonderful GadToolsBox. Thanks to the KreuzerSoft support team. Thanks to the Nations Capital Amiga Users Group (NCUAG). Major thanks to Dave at Buried Treasure in Rockville, MD. ********************************************************************* * Please patronize your local Amiga dealers (like Dave), everyone. ** * ** * Most of these people are NOT making tons of $$$$, so if you'd ** * like to keep a local presence in your area, GO BUY SOMETHING! ** ********************************************************************* Thanks to Commodore for the Amiga, and to Jan van den Baard for making the development of GUI's on the Amiga child's play. Thanks to Commodore for (finally) releasing the 3.0 Includes and Libraries! Thanks to Randy Thompson and Rhett Andersone for "Mapping the Amiga/ Second Edition". Finally, some type of 3.0 "C" book! @endnode @node contactingtheauthor "Contacting the Author" I'd really like to hear any feedback you have regarding PaletteTool. I can be reached via any of the following methods: - tkreuzer@delphi.com on the Internet - T.KREUZER on GEnie - via regular mail at: 6711A N. Washington Blvd. Arlington, VA 22213 @endnode @node legalstuff "Legal Stuff" PaletteTool Version 1.4 Copyright 1994 by Timothy B. Kreuzer. All rights reserved. You are hereby granted the freedom to distribute PaletteTool IF, AND ONLY IF the following rules are followed: - This doc file MUST be kept with the executable(s), and must include the above copyright notice. - You may NOT charge ANY fee for this program, other than the basic cost of distribution media and/or BBS access. Of course if you want to pursue selling this, feel free drop me a line. Fred Fish is hereby granted permission to include this program (and it's accompanying documentation) in his excellent collection of Amiga software. @endnode @node kreuzersoftproducts "KreuzerSoft Products" The following KreuzerSoft projects are (hopefully) available on a BBS near you: PST V1.0a - Public Screen utility for 3.0/AGA Fractal V1.2 - Mandelbrot set program for 3.0/AGA LyapunovSpace V1.2 - Lyapunov fractal program for 3.0/AGA Terrain V1.1 - 3-D fractal terrain program for 3.0/AGA FindColor V1.0a - "Color-by-Name" selector for 3.0/AGA Worm V1.1 - Port of SUN-Unix graphic toy for all Amigas DLA - Diffusion Limited Aggregation simulation for all Amigas Jimi - 8-color Jimi Hendrix image for your Workbench. MemTool - Memory monitor tool for the Workbench Reminder V1.1 - Timed reminder tool for the Workbench All for the incredibly low, low price of FREE! @endnode